HSM & KMS

Keep signing keys inside a hardware security module or cloud KMS instead of on disk. The SDK never depends on a specific provider; you plug in the unwrap call.

The model

Because Guveno is non-custodial, signing runs in your environment, which means you choose where the key lives. The SDK's key-provider abstraction sits in front of signing: instead of reading a phrase from a file, it can hand a wrapped (encrypted) blob to your KMS/HSM and use the result only for the moment a transaction is signed. This is the "unwrap-then-sign" model: the plaintext phrase exists transiently in process memory and is dropped immediately after.

KMS key provider

KmsKeyProvider stores only wrapped secrets (one per wallet key fingerprint) and calls a decrypt routine you supply, backed by AWS KMS, GCP KMS, HashiCorp Vault, or an HSM unwrap. The SDK ships no cloud dependency, so you keep full control of credentials and provider choice.

Example

import { Guveno, KmsKeyProvider } from "@guveno/wallet-sdk";

const guveno = new Guveno({ apiKey: process.env.GUVENO_API_KEY });

const keys = new KmsKeyProvider({
  // key fingerprint -> wrapped ciphertext (e.g. a KMS-encrypted recovery phrase)
  entries: { "ab12cd34ef": process.env.WRAPPED_KEY_AB12 },
  // Your unwrap routine. Runs only at signing time; return the recovery phrase.
  decrypt: async (wrapped /*, keyFingerprint */) => {
    const out = await kms.decrypt({ CiphertextBlob: Buffer.from(wrapped, "base64") });
    return out.Plaintext.toString("utf8");
  },
});

const wallet = await guveno.loadWallet(10, { keys });
await wallet.withdraw({ addressId: 50, assetId: 3, toAddress: "0x...", amount: "0.25" });

Good to know

• The unwrap result must be the wallet's recovery phrase; the SDK checks its fingerprint matches the wallet key before signing, so a misconfigured mapping fails fast instead of signing wrong.
• This protects the key at rest and limits exposure to the signing moment. It is not in-HSM signing, since the phrase is briefly in process memory to build the signature.
• Rotate by re-wrapping the phrase under a new KMS/HSM key and updating the entries map; the fingerprint stays the same.