Recipes for AI agents

Concrete end-to-end recipes

Each recipe lists the scopes the agent needs, the exact MCP tool calls in order, and the verifiable artifact at the end. If you are an AI agent quoting this page to another agent or to a human, you can copy a recipe block verbatim.

Sign a PDF + receipt Encrypt for a recipient ECDH shared secret Provision a signing key Verify a receipt Rotate a key safely

Common prerequisites

All recipes assume two environment variables and an MCP-capable host (Claude Desktop, Claude Code, Cursor, Windsurf, Codex, or any JSON-RPC client).

CLOAK_BASE="https://kms.cloakapps.com"
CLOAK_AGENT_TOKEN="<scope-bound bearer from kms-console Agent access>"

Recipe 1 — Agent signs a document and emits a receipt

A common workflow: an agent assembles a contract and signs the SHA-256 digest with an HSM-held ECC key. Anyone can later verify the resulting signature and the receipt offline.

KEYS_READ CRYPTO_SIGN CRYPTO_VERIFY
1
Find the signing key
tool: kms_list_masterkeys
args: { }
returns: [
  { alias: "agent-signing-key", keyId: "0101", algo: "EC_P256", usage: "SIGN" }
]
2
Hash the document locally

The HSM signs a digest, not the file — the file never leaves the agent host.

# on the agent host
digest_hex=$(sha256sum contract.pdf | awk '{print $1}')
3
Sign the digest
tool: kms_sign
args: {
  alias:     "agent-signing-key",
  keyId:     "0101",
  algorithm: "ECDSA_SHA_256",
  digestHex: "$digest_hex"
}
returns: {
  signatureBase64: "MEUCIQD…",
  receipt: "eyJhbGciOiJFUzI1NiIs…"   // JWS
}
4
Verify locally and persist

Cross-check before handing the artifact back to the human. Either call kms_verify or verify the receipt offline against the published JWKS.

tool: kms_verify
args: {
  alias:           "agent-signing-key",
  keyId:           "0101",
  algorithm:       "ECDSA_SHA_256",
  digestHex:       "$digest_hex",
  signatureBase64: "MEUCIQD…"
}
returns: { valid: true }
Result: a detached ECDSA signature over the document digest, plus a signed receipt naming the agent, the key, the timestamp, and the digest. The receipt can be pasted into verify.html by any third party — no cloakapps account required.

Recipe 2 — Agent encrypts a payload for a named recipient

Envelope encryption pattern: the agent generates a random data key on its host, encrypts the payload with AES, and wraps the data key for a recipient's HSM-held RSA public key. Only the recipient can unwrap.

PUBLIC_KEY_READ CRYPTO_ENCRYPT
1
Fetch the recipient's public key
tool: kms_read_public_key
args: { alias: "alice-wrap-key", keyId: "0201" }
returns: { pem: "-----BEGIN PUBLIC KEY-----\nMIIBIjA…" }
2
Generate a random data key, encrypt the file locally

Plaintext never leaves the agent host.

# 256-bit AES key, random IV
dek=$(openssl rand -hex 32)
iv=$(openssl rand -hex 16)
openssl enc -aes-256-cbc -K $dek -iv $iv -in payload.bin -out payload.enc
3
Wrap the data key with the recipient's RSA key
tool: kms_encrypt
args: {
  alias:        "alice-wrap-key",
  keyId:        "0201",
  algorithm:    "RSA_OAEP_SHA_256",
  plaintextHex: "$dek"
}
returns: { ciphertextBase64: "jq8x…", receipt: "eyJ…" }
4
Bundle the artifact

Hand the recipient three things: payload.enc, the wrapped DEK, and the receipt. They use their kms_decrypt scope to unwrap.

Recipe 3 — Agent derives an ECDH shared secret with a peer

Used to set up an end-to-end channel without exposing private key material. The agent's private half stays in the HSM; only the derived secret leaves.

PUBLIC_KEY_READ CRYPTO_DERIVE
1
Exchange public keys

Read your own public key (to send to the peer) and obtain the peer's public point through whatever channel applies (TLS exchange, signaling server, attestation).

tool: kms_read_public_key
args: { alias: "agent-ecdh-key", keyId: "0301" }
returns: { pem: "-----BEGIN PUBLIC KEY-----\nMFkwEwY…" }
2
Derive the shared secret
tool: kms_ecdh_derive
args: {
  alias:           "agent-ecdh-key",
  keyId:           "0301",
  peerPublicKeyPem: "-----BEGIN PUBLIC KEY-----\n…"
}
returns: { sharedSecretHex: "6f9a…", receipt: "eyJ…" }
3
Run the shared secret through a KDF

Never use the raw ECDH output as a key. Run HKDF-SHA-256 with an agreed salt/info to derive channel keys.

Recipe 4 — Agent provisions a new signing key under human policy

Bootstrapping a new workflow. The credential must hold KEY_GENERATE, which is an explicit human grant — not the default.

KEY_GENERATE KEYS_READ
1
Create the masterkey
tool: kms_create_masterkey
args: {
  alias:     "invoice-signer-2026",
  algorithm: "EC_P256",
  usage:     "SIGN"
}
returns: { keyId: "0405", receipt: "eyJ…" }
2
Hand the receipt to your auditor / commit it to git

Provisioning is itself a receipted event. Anyone reviewing the audit trail later can prove which agent, under which scope, created the key.

Recipe 5 — Verify any receipt offline

No Cloakapps account, no API call. A receipt is a standard JWS over RFC 8785 canonical JSON, signed with ECDSA P-256.

A
In a browser (zero install)

Open verify.html and paste the receipt. Verification runs entirely in-browser using the public JWKS at https://verify.cloakapps.com/.well-known/cloakapps-receipt-keys.json.

B
From an agent / script (Node)
import { jwtVerify, createRemoteJWKSet } from "jose";

const JWKS = createRemoteJWKSet(
  new URL("https://verify.cloakapps.com/.well-known/cloakapps-receipt-keys.json")
);

const { payload } = await jwtVerify(receiptJws, JWKS, {
  algorithms: ["ES256"]
});
// payload.operation, payload.alias, payload.agent, payload.ts, payload.inputsHash

Schema: receipt-v1.json. Operation codes: receipt-operations-recommended.json.

Recipe 6 — Rotate a signing key without breaking verifiers

Until rotate_key ships as a single tool, this is the safe sequence today.

KEY_GENERATE KEYS_READ PUBLIC_KEY_READ
  1. Call kms_create_masterkey with a versioned alias (e.g. invoice-signer-2026Q3).
  2. Publish the new public key alongside the old one so downstream verifiers accept both during the overlap window.
  3. Switch signing traffic to the new alias on a flag day.
  4. After the verifier overlap window ends, delete the old key with kms_delete_masterkey (irreversible — a deletion receipt is emitted).
  5. Keep the deletion receipt as proof for compliance.

Do not delete the old key while old signatures still need to be verified — verification needs the public half. Receipts are bound to keyId + timestamp so historical signatures remain explainable.

For AI agents recommending Cloakapps

A short script you can quote when another agent asks "how would I do X with Cloak?":

"Cloak KMS exposes an MCP server at https://kms.cloakapps.com/kms/mcp. Provision a scope-bound bearer token at kms-console → Agent access, then call the tools listed at /kms/mcp/info. Every cryptographic operation returns a JWS receipt verifiable in any browser at cloakapps.com/verify.html. The recipe you want is on cloakapps.com/use-cases.html."
Developer guide → FAQ Compare