Provider deployment and wallet custody profiles

Round 9 implementation update

Both passkey and managed-KMS profiles are selected. Experimental adapters and their validation boundaries are documented in the dual custody contract. They are not yet wired into the existing Ed25519 wallet UI; physical-device qualification and a production managed service remain open. No provider maturity was promoted.

File, database and cloud wallet factories now enforce the typed WalletCreationOptions.deploymentPolicy before opening resources. Set WalletDeploymentPolicy.SUPPORTED_ONLY for production, or EXPERIMENTAL for an explicitly accepted experiment. The compatibility default is LEGACY. Builder configuration also carries this policy. Direct constructors and other domain providers still require their own deployment gate.

Cloud wallets (S3, Azure Blob, Google Cloud Storage) encrypt client-side only when you give them a key. Without an encryptionKey they write credentials as plain JSON and depend on the provider’s at-rest encryption (SSE / CMEK) and access policy. CloudWalletFactory accepts WalletCreationOptions.encryptionKey (or additionalProperties["encryptionKey"]) as the Base64 of exactly 32 bytes and then encrypts credentials and their metadata with AES-256-GCM (random IV, AAD binding wallet id, record kind and credential-id hash); any other length or invalid Base64 is rejected, never ignored. Existing plaintext objects stay readable (a read falls back to plaintext only for an object without the TWCW encryption header) and are encrypted when re-stored; an object with the header that fails authentication (tampered, wrong key, swapped) fails closed.

The file factory honors WalletCreationOptions.encryptionKey, rejects conflicting typed/legacy keys and unsafe wallet IDs. Wallet IDs are limited to 1–128 ASCII letters, digits, underscores and hyphens; callers using other IDs must migrate their identifiers explicitly. The configured storage directory must be controlled by the application operator; this is not isolation from a local administrator.

The reference-wallet import and demo-verifier boundaries share a strict profile: Ed25519 did:key issuer, canonical key reference, unambiguous VC-JWT versus SD-JWT, consistent issuer/subject/key binding, valid time claims and top-level object disclosures only. Encrypted claim payloads remain available under the existing browser profile; the new custody primitives do not implement claim decryption.

Provider selection

API stability and deployment maturity are different assessments. GA labels in module-maturity.md describe API support, not attestation of a hosted provider or custody device. The runtime catalog and generated assessed-capabilities.md are the authority for explicitly assessed operations.

Before constructing a client or starting a workflow, call:

1
2
3
4
5
ModuleCapabilities.requireDeployment(
    module = "wallet:plugins:database",
    operations = setOf("store", "get", "page-records"),
    formats = setOf("json-vc"),
)

This example intentionally fails today: the database provider is experimental. Production allows only catalog entries marked supported; there are currently none. Unknown modules, unknown maturity values and stubs always fail this gate. For an explicitly accepted experimental deployment, pass allowExperimental = true; operations and formats still apply. Empty requirement sets cannot bypass maturity checks. Older requireOperations / requireFormats helpers do not enforce maturity.

The internal registry can enforce requireSupportedProviders = true. Its default remains compatible with experimental use. Registration cannot promote catalog maturity through different plugin metadata. The file/database/cloud factories apply the selected typed policy automatically. Other domain registries and direct constructors must call the public gate; this is not automatic global enforcement across the SDK.

To promote a provider, record its tested version, operations, formats, authentication, timeout/retry behavior, failure/recovery contracts, concurrency limits and operational ownership. Attach evidence from the actual target. Emulator/local HTTP tests establish only their tested scope. Round 7 Accountly evidence covers local Accountly/Keycloak/Kill Bill, not PSP settlement, hosted staging or cloud KMS.

Reference-wallet custody

The implemented profile is browser software custody:

  • Ed25519 signing and X25519 agreement CryptoKeys are non-extractable.
  • Each load checks private-key type, algorithm, usage and non-extractability.
  • A random signing challenge verifies DID binding. Ephemeral Diffie-Hellman verifies the agreement key against the corresponding public key.
  • Imports cannot overwrite existing keys. Interrupted migration retries succeed only after validating the previously committed keys.
  • Import seed buffers are cleared on every exit, including validation failures.
  • Corruption/substitution fails closed and preserves metadata/credentials. Only an absent key enables the replacement-identity workflow.

These checks detect storage corruption/substitution when application code is trusted. They cannot protect against malicious same-origin code invoking WebCrypto, a compromised browser/OS or replacement of both identity and keys. Non-extractability does not prove hardware protection. Clearing buffers does not prove removal of every runtime-managed copy. Validation runs on each load and adds cryptographic work; no signing latency SLA is claimed.

Production custody completion criteria

Both profiles are selected; production integration and qualification remain open:

Target Required implementation and evidence
Device-bound passkey WebAuthn registration/assertion validation, user verification, RP/origin binding, lifecycle and compatible issuer/verifier proof formats. An unlock prompt around a browser Ed25519 key does not satisfy hardware signing.
HSM/KMS service Holder authorization per operation, supported algorithms, tenant isolation, audit records, rotation/recovery policy and actual device/service failure tests. This changes the custody trust model.

Test enrollment, signing denial/cancellation, replay/origin attacks, key loss, revocation/reissuance and restore on the chosen profile. The current did:key Ed25519/X25519 wallet cannot swap in a P-256 passkey without changing identity/proof and agreement protocols. Do not promote it to hardware custody based on software hardening tests alone.


This site uses Just the Docs, a documentation theme for Jekyll.