[EPIC](plugins) Crypto Keystore Storage as plugin for L2-4 Key Material

[nnicora]

I want to implement a pluggable keystore architecture so that L2, L3, and L4 (crypto edge) key material can be securely stored in different backend systems.

Context: OpenKCM manages a multi-tier key hierarchy where different keys have different persistence requirements. By move to a plugin-based model, we decouple the core cryptographic logic from the storage implementation, starting with In-Memory and OpenBao Secret Storage as the initial MVP providers.

---

🎯 Business Value

• Operational Flexibility: Enable multi-cloud and hybrid-cloud deployments by allowing backend-specific storage (e.g., AWS KMS, PostgreSQL, or local HSM).
• Security Tiering: Securely store persistent L2/L3 keys in a hardened vault like OpenBao, while keeping transient L4 edge keys in high-performance memory.
• Future-Proofing: Easily integrate new storage backends without modifying the OpenKCM Crypto core.
• Compliance: Support diverse data sovereignty requirements by selecting storage plugins based on regional or tenant policies.

---

🏗️ Architecture Design

The system will utilize a Provider Interface pattern. The Crypto Core will interact with a Keystore interface, which is fulfilled by specific plugin drivers at runtime.

1. The Keystore Plugin Interface

Every plugin must implement the following gRPC/Go contract:

• StoreKey(id, material, metadata): Securely persist encrypted key material and tags.
• RetrieveKey(id): Fetch key material for use in crypto operations.
• UpdateKeyMetadata(id, metadata): Update lifecycle fields (e.g., status, expiration).
• DeleteKey(id): Permanently remove/shred key material.
• ListKeys(filter): Query keys based on ownership (tenant/service) or type (L2/L3/L4).

2. Standardized Key Metadata

Plugins must persist a standard set of metadata to ensure consistency across backends:

• Identifier: Unique Key ID and Version.
• Classification: Key Type (L2, L3, L4), Algorithm, and Key Size.
• Lifecycle: Status (Active, Deprecated, Retired) and Expiry.
• Ownership: Owner ID (Tenant/Service/Node).

---

🚀 Functional Requirements

Milestone 1: Plugin Framework & SDK

• Define the Protobuf/gRPC interface for KeystoreOperations.
• Implement the PluginManager to handle dynamic loading and health-checking of backends.
• Refactor the Crypto Core to use the Keystore interface for all L2-L4 persistence.

Milestone 2: MVP Plugin Implementations

• InMemory Plugin: A non-persistent backend for rapid testing and volatile L4 crypto-edge material.
• OpenBao Plugin: A production-grade backend utilizing OpenBao Secret Storage for encrypted L2/L3 keys.

Milestone 3: Routing & Configuration

• Support loading plugin settings via config.yaml or environment variables.
• Implement Default Routing: e.g., default L2/L3 keys to OpenBao and L4 keys to InMemory.
• Ensure the system handles backend "Sealed" or "Unavailable" states with graceful error propagation.

---

🛡️ Non-Functional Requirements

• Security: Key material must be encrypted before being sent to the storage plugin (Envelope Encryption).
• Performance: Keystore operations must include a caching layer to minimize latency for frequent L3/L4 lookups.
• Reliability: Implement transactional semantics (or compensations) to prevent orphaned keys if a storage operation fails.

---

✅ Acceptance Criteria

• Keystore plugin interface is fully defined and integrated into the OpenKCM SDK.
• Both OpenBao and InMemory plugins successfully store and retrieve L2-L4 key material.
• Key metadata remains consistent and searchable across different backends.
• Configuration allows for the runtime swapping of storage providers without code changes.
• Unit and Integration tests confirm graceful recovery from plugin connectivity failures.