docs: add HSM integration walkthroughs for CloudHSM/KeyVault/GCP HSM/Zymbit (closes #4)

[abhicris]

Closes #4.

Follow-up to the clarification on issue #4 — makes the README's "HSM compatible" claim concrete and gives integrators a working starting point.

What this PR says about "HSM compatible"

The key observation, cross-checked against the code:

Every Config in this repo (CMP / FROST / LSS / Doerner / Ringtail) exposes MarshalBinary() / UnmarshalBinary() — see protocols/cmp/config/marshal.go and the equivalents in other protocols. From the HSM's perspective, a Config is opaque bytes. The HSM is a storage + access-control boundary, not a compute boundary: the share leaves the HSM encrypted, is decrypted into process memory, participates in the MPC rounds in the clear, and the new ciphertext is written back.

This is the first thing reviewers of issue #4 were asking for — a truthful statement of what "HSM compatible" means so they can decide whether this library fits their threat model.

Recommended adapter interface

A small ShareStore interface that any HSM integration can implement. It matches the abstraction pattern used in luxfi/mpc's pkg/hsm — documented here so integrators can adopt the pattern without reading a second repo:

type ShareStore interface {
    Put(ctx context.Context, orgID, walletID, partyID string, share []byte) error
    Get(ctx context.Context, orgID, walletID, partyID string) ([]byte, error)
    Rotate(ctx context.Context, orgID, walletID, partyID string) error
}

Four integration walkthroughs

Each follows the same structure — prereqs; credential plumbing (preferred = workload identity / IRSA / managed identity, fallback = short-lived env vars); key-share storage contract (what goes in the HSM vs what stays on disk); a runnable Go example against the actual SDK; known limits (FIPS level, rate limits, cost, cold start):

1. AWS CloudHSM — FIPS 140-2 L3; envelope mode with AWS KMS; example against aws-sdk-go-v2/service/kms with EncryptionContext binding ciphertext to (org_id, wallet_id, party_id).
2. Azure Managed HSM / Key Vault — FIPS 140-2 L3 on Managed HSM (and the explicit warning that Standard Key Vault is only L1 and is insufficient for many regulated contexts); example against azure-sdk-for-go/sdk/keyvault/azkeys using WrapKey with RSA-OAEP-256.
3. GCP Cloud HSM — FIPS 140-2 L3; example against cloud.google.com/go/kms with AdditionalAuthenticatedData binding ciphertext to the same tuple.
4. Zymbit SCM — edge / on-prem; cgo example against zkapputils; explicit note that Zymbit is not FIPS certified as of this writing — check current specsheet before deploying to regulated environments.

Runtime isolation section

An honest section on Nitro Enclaves and SGX for threat models where the share must never exist unencrypted in host memory — with the caveat that runtime isolation is an order of magnitude more work than envelope encryption, and most integrators should start with envelope-plus-MPC-distribution and add enclaves later if the threat model demands it.

Summary table

Single table comparing FIPS level, throughput, and cost across the four providers, so integrators can pick the right option at a glance.

Cross-links

This guide is cross-linked from docs/audit.md § Deployment Considerations in the companion PR (#8). Together they answer the two open security-documentation issues on the repo.

On scope

I deliberately did not add pkg/hsm/adapters/ source files in this PR — there's no existing pkg/hsm/ tree in this repo today, and an interface-plus-four-adapters module is a larger (code-owning) design change that should go through its own design discussion. This PR lands the integration guide that answers #4 directly; if maintainers want adapter code in-tree, happy to follow up as a separate PR with the ShareStore interface and the four adapter implementations as a new package.