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.