Azure Key Vault

Azure Key Vault can sit behind both secrets and keys: it holds your provider keys, and its keys wrap the data keys MainSDK creates for each record. Pick it when your app runs on Azure. Note the two driver ids: azure-key-vault for secrets and azure-keyvault for keys.

secrets:
  driver: azure-key-vault

keys:
  driver: azure-keyvault

Before you start

1. Create a key vault in each Azure region your data must stay in, at least one per MainSDK region (US, EU and India) if you use it for keys.
2. Add your app's secrets, and for keys create one key per region.
3. Give the app a managed identity, or workload identity federation outside Azure, rather than a client secret.
4. Grant that identity read access to the secrets, and wrap and unwrap access to the keys, and nothing more.

Configure

secrets:
  driver: azure-key-vault        # [to be decided] vault and other driver settings are not specified yet
email:
  key: secret:RESEND_API_KEY     # suggested name
keys:
  driver: azure-keyvault         # note: no hyphen in the keys driver id
  key:                           # [to be decided] confirm the identifier form the driver takes
    us: https://pinecart-us.vault.azure.net/keys/pinecart-us
    eu: https://pinecart-eu.vault.azure.net/keys/pinecart-eu
    in: https://pinecart-in.vault.azure.net/keys/pinecart-in
  per-user: true
  rotate: 365d

Use it

import { keys, secrets } from "mainsdk";

export async function partnerToken() {
  return secrets.get("PARTNER_API_TOKEN");   // from Key Vault, server only
}

export async function sealNote(note: string, user: { id: string }) {
  return keys.encrypt(note, { owner: user, region: "eu", label: "personal" });
}

Local development and testing

Use the local secrets and keys drivers in development; mainsdk check refuses the local keys driver in production with MAIN-KEYS-0001. In tests, createTestApp() from @mainsdk/testing runs both on in-memory fakes, and chaos.on("secrets", { outage: true }) simulates Key Vault being down.

What MainSDK adds on top

• Secrets server only, redacted everywhere, and served from memory (last good value) during an outage.
• A data key per record, one wrapping key per region, every key use audited, automatic rotation.

See Secrets and Encryption keys.

Limits and notes

• The secrets driver comes with the config-secrets spec (phase 1); the keys driver with the keys spec (phase 1), after AWS KMS and Vault Transit.
• Azure Managed HSM comes with the hsm-keys spec in phase 3.
• secrets.raw() and keys.raw() return the provider client; mainsdk check lists every use.

Swap to or from it

keys:
  driver: azure-keyvault   # was aws-kms

FAQ

Why two different driver ids? The specs name them that way: azure-key-vault under secrets and azure-keyvault under keys. Use each in its own block.

Can one vault serve every region? For keys, MainSDK wants one wrapping key per region, so use a vault in each region your data lives in.

Next

• Secrets and Encryption keys
• AWS KMS, Google Cloud KMS and HashiCorp Vault