feat: add an optional OpenBao Transit KMS backend for server agents

[sign-mark]

Context

CREDEBL Platform now supports OpenBao KV secret storage through credebl/platform#1679, while server-side Holder Cloud Wallet and organization Issuer agents still use Askar as their only Credo KMS backend.

Credo 0.6.2 already supports multiple KeyManagementService backends through KeyManagementModuleConfig. Askar registers its own backend through this mechanism, so an OpenBao backend can be added without replacing Askar storage or changing Holder/Issuer business APIs.

Related work:

• feat: add OpenBao for credential secret storage platform#1679 — OpenBao KV secret storage
• Cloud-wallet service extensibility platform#1352 — Cloud Wallet extensibility
• Cloud/Web Wallet Support platform#1442 — Cloud/Web Wallet support
• Expose pluggable Credo KMS backends in the Mobile SDK mobile-sdk#124 and feat(core): support additional Credo KMS backends mobile-sdk#125 — pluggable Credo KMS backends for the Mobile SDK

Problem

Server agents currently have no supported way to keep DID/VC signing keys outside the Agent process and Askar wallet. There is no OpenBao Transit integration, no backend selection policy for Holder versus Issuer agents, and no stable mapping between Credo KMS key ids and OpenBao Transit keys.

This prevents deployments from using a vendor-neutral, centrally audited signing boundary while preserving the existing CREDEBL Agent APIs.

Proposed architecture

Add an optional OpenBaoKeyManagementService implementing Credo 0.6.2 Kms.KeyManagementService.

The Agent should continue registering Askar for encrypted record storage and backward compatibility. When enabled, OpenBao is registered as an additional KMS backend. Backend selection is explicit and policy-driven; existing installations that omit OpenBao configuration retain current Askar behaviour.

Target flow:

Holder or Issuer operation
-> Credo KeyManagementApi
-> OpenBaoKeyManagementService
-> OpenBao Transit
-> OpenBao-managed key or an external KMS/HSM key

The Platform Cloud Wallet service must not call Transit directly. KMS routing belongs in Agent Controller so DID, DIDComm, OID4VC, JSON-LD, status-list, raw-signing, and X.509 paths share one key-management boundary.

Phase 1 scope

• Add an OpenBao Transit client with bounded timeouts and typed errors.
• Authenticate using a machine auth method suitable for production, with token caching and renewal; do not log credentials or client tokens.
• Implement a stable namespaced key-id format that can route a key back to OpenBao without storing private key material in Platform records.
• Implement and test the Credo operations required for DID/VC signing: createKey, getPublicKey, sign, verify, and delete or disable according to an explicit lifecycle policy.
• Report unsupported operations and algorithms through isOperationSupported; do not silently fall back to Askar for an OpenBao key id.
• Initially cover the algorithms required by agreed Holder/Issuer flows, with an explicit compatibility matrix. At minimum evaluate Ed25519 and ECDSA P-256.
• Register OpenBao after Askar by default so existing deployments remain backward compatible.
• Allow an explicit configuration policy to select OpenBao for organization Issuer agents and, separately, Holder Cloud Wallet tenants.
• Preserve Askar as the storage backend even when OpenBao is selected for signing keys.
• Add unit tests for routing, algorithm mapping, signature encoding, tenant/organization namespace isolation, token redaction, timeout/error mapping, and fail-closed behaviour.
• Add an opt-in integration test against a real OpenBao Transit instance.

Security requirements

• Private key material generated in OpenBao must never be returned to or persisted by Agent Controller or Platform.
• Holder tenant and Issuer organization key namespaces and policies must be isolated.
• A key id belonging to one tenant or organization must not be usable from another AgentContext.
• OpenBao authentication credentials, tokens, request bodies containing sensitive material, and signatures must be redacted from logs as appropriate.
• Key deletion, disabling, rotation, and recovery semantics must be documented before production enablement.
• Network or OpenBao failure must fail closed; an operation for an OpenBao key must never be retried with an Askar key.
• Audit events must carry a correlation identifier that can be matched with Platform and Agent logs.

Acceptance criteria

• Existing Askar-only Agent configurations behave unchanged.
• A configured Agent can create an OpenBao-backed signing key and receive only its key id and public JWK.
• Credo can sign and verify using that key through KeyManagementApi.
• The same OpenBao-backed key can be used by at least one representative Issuer issuance flow and one Holder proof or OID4VC binding flow.
• Cross-tenant and cross-organization key use is rejected by tests.
• Unsupported algorithms and operations fail explicitly without fallback.
• Unit, build, and opt-in live OpenBao integration tests pass.
• Operator documentation covers Transit setup, policies, authentication, backup/recovery, rotation, observability, and rollback to an Askar-only configuration for new keys.

Out of scope

• Replacing Askar record storage.
• Silently migrating or exporting existing Askar private keys.
• Making OpenBao mandatory before the backend has completed interoperability, performance, recovery, and failure-mode validation.
• Direct AWS KMS API compatibility.
• Claiming HSM protection unless the configured OpenBao deployment and external-key provider prove it.

Delivery approach

1. Architecture and algorithm/key-id mapping document.
2. OpenBao Transit client and Credo backend with focused unit tests.
3. Optional Agent configuration and backend registration.
4. Issuer and Holder integration tests.
5. Production operations and recovery validation before changing any default.