# Merchant Crypto MCP Container

The merchant crypto MCP container is an optional, merchant-hosted helper for
agents that cannot embed the Cheqi SDK directly. Run it only inside
merchant-controlled infrastructure.

## Boundary

Cheqi MCP is responsible for:

- matching the customer to temporary owner-device recipients
- accepting the final per-device ciphertext set
- explaining the required flow and terms


The merchant crypto helper is responsible for:

- accepting the definitive receipt input inside merchant infrastructure
- serializing that input consistently
- creating a fresh AES-256 content key per owner device
- encrypting the input with AES-GCM
- wrapping each content key with the matching device public key
- returning only the fields required for encrypted submission


It must not move receipt plaintext, private keys, or unwrapped symmetric keys
into Cheqi infrastructure.

## Current handoff

Call Cheqi MCP `match_customer`, then pass the same definitive receipt input and
the complete returned device-recipient list to the merchant-hosted helper.

For each device, the helper returns:

```json
{
  "deviceRecipientId": "rcpt_temporary",
  "encryptedContent": "base64-aes-gcm-ciphertext",
  "encryptedAesKey": "base64-rsa-oaep-wrapped-aes-key"
}
```

Collect those entries without adding, removing, or reordering their recipient
identity, then call Cheqi MCP `submit_encrypted_receipt`:

```json
{
  "matchId": "match_opaque",
  "deviceDeliveries": [
    {
      "deviceRecipientId": "rcpt_temporary",
      "encryptedContent": "base64-aes-gcm-ciphertext",
      "encryptedAesKey": "base64-rsa-oaep-wrapped-aes-key"
    }
  ]
}
```

The helper does not generate a server receipt template or `templateHash` for
this route. Final CHEQI and UBL documents and their canonical hashes are
generated on owner devices.

## Operational guidance

- Keep the container on a private network and require authenticated MCP access.
- Never expose it directly to the public internet.
- Do not store Cheqi recipient IDs; they are temporary and match-scoped.
- Do not reuse a symmetric key across devices.
- Keep logs free of plaintext receipt contents and cryptographic key material.
- Reject an expired match and rerun `match_customer` instead of reusing its
recipients.
- Ensure the output contains exactly one entry per owner device returned by the
match.


## When to use this

Use the container when an MCP-native host requires a separate cryptographic tool
boundary. Use an official SDK when cryptography can be embedded in the merchant
application.