Investigate Move to Stateless Key Management for Rust & Web Clients

[dagarcia7]

Summary

Hi team,

After looking to implement #908, I realized there's a lot of room for improvement in the way the web and rust clients handle user keys. I'd like to propose we investigate what it takes to move from our current stateful key management model to a stateless approach for both the Miden rust and web clients. This change would simplify interfaces, improve separation of concerns, and enhance security posture by delegating key management to downstream consumers (wallets, dApps, etc.).

Current State

Today, both the Rust and web clients:

• Are responsible for generating and storing public/private keypairs.
• Store these keys unencrypted, leaving security enforcement up to the client.
• Require workaround logic (e.g., fetchAndCacheAccountAuthByPubKey in the web client) due to synchronous signature generation in Rust.

For example:

When a transaction is triggered in the web client, it has to call fetch and cache an account for the synchronous get_signature call to be able to get the signing key.

This pattern adds complexity to seemingly simple operations like signMessage, which would either:

• Require an accountId to be passed in (muddying the interface), or
• Require a concept of an "active key" to be set globally (adding shared mutable state).

Stateless Proposal

Under a stateless model, the clients would:

• Still generate keypairs (if needed), but would not be responsible for persisting or managing them.
• Accept private keys (or signatures) as parameters to downstream actions like sendTransaction, getSignature, signMessage, etc.
• Delegate encryption, passphrase handling, and secure storage to the application layer.

In this model:

• The responsibility of securing and storing the private key moves to external consumers (dApps, wallets).
• get_signature(public_key) becomes obsolete; instead, the signing logic would operate on a provided private key or signature directly.

Benefits

Security: Removes assumption that the client can securely store keys; encourages explicit encryption/storage flows.

Simplicity: Eliminates the need for caching accounts, global key state, or indirection in interfaces.

Flexibility: Supports integration with a wider range of key management flows (e.g., hardware wallets, passphrase-based encryption, external keystores).

Testability: Stateless APIs are easier to test in isolation without requiring mock storage/state.

Conclusion

I know this is a big ask, but I'm hopeful that because there are not too many places where get_signature is called, that it should be in the realm of possibility to at least make this part of the client stateless. I believe if we are able to achieve this, I'd feel much better security-wise (at least from the client's perspective), but this would also help untangle the responsibility of key management and make a clear cut between what apps are responsible for and what the client is responsible for. This would in turn help simplify the APIs from the web client perspective and put the onus on the consumers as to how they want to use the keys they generate. Finally, if we wanted, we could even include utilities to aid users like encryptSecretKeyWithPassphrase, or things like that to simplify their key handling, but that would be further down the line.

I could also be way off the mark and not be considering something or have something wrong with what I have above 😅

In any case, let me know what y'all think!

[tomyrd]

get_signature(public_key) becomes obsolete; instead, the signing logic would operate on a provided private key or signature directly.

I could be wrong, but we can maybe keep the get_signature interface and still have a stateless model by having a temporary TransactionAuthenticator that stores the provided key pairs for the specific transaction. If the VM cannot find a specific key it will fail and we can notify the user that a key pair is missing.

[igamigo]

To comment on a couple of the assumptions:

Today, both the Rust and web clients:

• Are responsible for generating and storing public/private keypairs.
• Store these keys unencrypted, leaving security enforcement up to the client.
• Require workaround logic (e.g., fetchAndCacheAccountAuthByPubKey in the web client) due to synchronous signature generation in Rust.

The Rust client does not generate nor store keypairs anywhere. In terms of the actual Client struct, as far as it is concerned, accounts are generated by the user and so the account metadata (including authentication) is up to the user to handle.
We provide the Keystore which is somewhat opinionated and could use some improvements (we have an issue for encryption as one of these improvements though this could end up still being quite opinionated). The Keystore is mainly used in the CLI to provide persistence and, on execution, transaction authentication via the TransactionAuthenticator implementation (as @tomyrd mentions above).

In this model:

• The responsibility of securing and storing the private key moves to external consumers (dApps, wallets).
• get_signature(public_key) becomes obsolete; instead, the signing logic would operate on a provided private key or signature directly.

As implied above, this should mostly already be the case.
Overall, there is nothing that the Rust Client enforces in terms of key management and so the web client should be in a good place to implement its own solution. What this solution would look like is an interesting topic, but making it strictly analogous to something like what it looks like in Ethereum or Solana might not be the best approach since the concept of authenticating a transaction is different here. This issue should be quite relevant for discussing what it means authenticating an account strictly in the context of transaction execution (ie, not necessarily signing arbitrary messages though they are obviously at least superficially related).

[evanmarshall]

I think there's some confusion so I'd like to be pretty specific. The get_signature method here is Generic but it's not Stateless

fn get_signature(
        &self,
        pub_key: Word,
        message: Word,
        account_delta: &AccountDelta,
    )

A Stateless signature would look like:

fn get_signature(
        secret_key: AuthSecretKey,
        message: Word,
        account_delta: &AccountDelta,
    )

This forces clients to implement a keystore like here in the rust client or here in the web client.

Overall, there is nothing that the Rust Client enforces in terms of key management and so the web client should be in a good place to implement its own solution. What this solution would look like is an interesting topic, but making it strictly analogous to something like what it looks like in Ethereum or Solana might not be the best approach since the concept of authenticating a transaction is different here.

Because it's Generic, you can of course implement any keystore you want to use but every client implementation is going to have to make some decisions about what that keystore looks like. What @dagarcia7 and I are advocating is that the Client implementation shouldn't have to care about how keys are stored.

In the Web Client, this leads to some complication. Sometimes as a DApp developer, a default solution like IndexedDB is sufficient. In the case of a wallet chrome extension, we have to be extremely specific of how these keys are stored and exposed. We can't run a full client in a service worker as the service worker is blocking and we never want to expose private keys to the content scripts which is where the client has to run. Ideally, we'd be able to have small stateless parts of the SDK like generating keys or signatures and run those in the service worker.

What this ends up looking like right now is that we have to implement a different keystore just for the Miden Wallet which will be extremely opinionated. Anyone who has a slightly different opinion about where private keys are stored will need to fork the Web Client and reimplement their own keystore. I see this is a challenge when someone wants to create a Mobile Client or use the keychain or create a NodeJS client. Having a Generic keystore lets implement anything you could want or you could make it stateless and then users don't have to fork code and reimplement clients in order to use it.

[igamigo]

I see what you mean. I'm afraid I might not be familiar enough with how a wallet is supposed to function in terms of requirements and the constraints related to the browser environment.

What @dagarcia7 and I are advocating is that the Client implementation shouldn't have to care about how keys are stored.

In the case of a wallet chrome extension, we have to be extremely specific of how these keys are stored and exposed.

What is currently blocking the wallet from being specific about how the keys are stored? Is it mainly the sync API? This has been a long-running problem in general (making the VM have async functions comes with its own set of challenges; Tomas opened an issue some time ago), but I believe it is planned for the next iteration of the VM (0xMiden/miden-vm#1558). I still don't think the client imposes any restriction in terms of how keys are stored, though (perhaps with how they are provided?). To recap, get_signature is called from within the transaction execution context as part of a VM event. The idea is to not expose private keys in this context, so the public key is read from and provided as part of the callback. The user can then sign the message if they prefer, or fail it for whatever reason (for instance, an unexpected AccountDelta).

If the API not being async is the main blocker, then I think this is a different problem statement but could a solution be to try and make it async? I realize that would still make the API itself stateful, but I think Dennis's points about the workarounds get addressed.

Otherwise, I think there could definitely be alternatives to how transaction authentication is implemented. For example, I think the private key used to be provided through the advice map, though I think it was not used for signing over the account delta. Some of the motivations by @bobbinth to move away from this can be found in this issue. For this it might make sense to open an issue on miden-base or maybe better, continue the discussion in the authencation issue I linked in my previous comment.

What this ends up looking like right now is that we have to implement a different keystore just for the Miden Wallet which will be extremely opinionated

Would this be a problem considering the more recent discussions related to making the webclient more opinionated and abstracted away? Additionally, could there be different implementations with good defaults that the user can choose from or choose to implement their own? I'm not sure I see why you'd need to fork the web client for having new ways of providing keys.

[bobbinth]

fn get_signature(
        &self,
        pub_key: Word,
        message: Word,
        account_delta: &AccountDelta,
    )

A Stateless signature would look like:

fn get_signature(
        secret_key: AuthSecretKey,
        message: Word,
        account_delta: &AccountDelta,
    )

Wouldn't this require the client to store secret keys? Basically, the way get_signature() works, is that the call is made from inside the VM (when transaction code needs to sign something) and the VM doesn't have the private keys so it asks someone else to sign the message via the get_signature() call. For the VM to pass the private key into get_signature(), it would need to have the private key in its memory.

I think I am probably misunderstanding something - specifically about who'd call the get_signature() method in the proposed model.

[bobbinth]

Security: Removes assumption that the client can securely store keys; encourages explicit encryption/storage flows.

Simplicity: Eliminates the need for caching accounts, global key state, or indirection in interfaces.

Flexibility: Supports integration with a wider range of key management flows (e.g., hardware wallets, passphrase-based encryption, external keystores).

Testability: Stateless APIs are easier to test in isolation without requiring mock storage/state.

I think I'm not fully understanding the proposal, but the stated benefits is exactly what we are trying to achieve with TransactionAuthenticator::get_signature() interface. The main problem with it though is that it is sync rather than async.

Basically, the intent of the TransactionAuthenticator interface is that the client doesn't need to store or manage keys in any way - this is left to the implementations of TransactionAuthenticator to define this. These implementations could be based on in-memory key storage, secure enclaves, hardware wallets, or even air-gapped wallets.

And the problem, again, is that it doesn't quite work in the context of the WebClient because get_signature() is sync which requires you guys to create an extra level of indirection and store the keys in a store that is accessible via sync interface.

Assuming the above is correct (and let me know if it isn't), this is a broader problem that we are trying to solve (and hopefully, will solve in the next few weeks) by making requests emitted by the VM to be async. In fact, once this problem is solved, we'll be able to have more methods work similar to how get_signature() works which will unblock us in other directions (e.g., we'd finally be able to implement lazy account loading).

[evanmarshall]

We really appreciate the clarification. We can modify create_client in the WebClient to take in function parameters for add_key, get_key, and get_signature. It probably makes sense to address this as you mention after the async. I think this will work well with the wallet because we can support both the ServiceWorker callbacks that we will need as well as providing a default option for web client users without complicated flows.

We'll create an issue to address this as well as create a standalone:

fn get_signature(
        secret_key: AuthSecretKey,
        message: Word,
        account_delta: &AccountDelta,
    )

That we will use in the service worker.

Thanks for clearing this up. We now have a much better understanding.