MPC secret storage

MPC splits each secret's DEK into shares so one compromised holder cannot decrypt. It layers on top of the standard HSM envelope encryption and is set per vault. The custody mode is immutable once set.

• 2of2_client_custody: XOR split between the server HSM and you; you hold a client_share
• 2of3_multi_hsm: Shamir 2-of-3 across GCP, AWS, and Azure; no client share
• 2of3_client_custody: Shamir 2-of-3 with two HSMs plus your client share

1. 1

   Export your API key and vault ID. Use your vault UUID from 1claw vault list or Foundations.

   bash Copy

   export ONECLAW_API_KEY="1ck_your_key_here"
   export VAULT_ID="your-vault-uuid"

2. 2

   Exchange your API key for a bearer token.

   bash Copy

   export TOKEN=$(curl -s -X POST https://api.1claw.co/v1/auth/api-key-token \
     -H "Content-Type: application/json" \
     -d "{\"api_key\":\"$ONECLAW_API_KEY\"}" | jq -r .access_token)

3. 3

   Enable MPC with XOR client custody. This choice is permanent for the vault.

   bash Copy

   curl -s -X POST https://api.1claw.co/v1/vaults/$VAULT_ID/mpc \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"custody_mode":"2of2_client_custody"}'

4. 4

   Write a secret. The PUT response includes a base64 client_share you must keep. Capture it from the response.

   bash Copy

   RESPONSE=$(curl -s -X PUT https://api.1claw.co/v1/vaults/$VAULT_ID/secrets/api-keys/stripe \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"value":"sk_live_abc123","type":"api_key"}')
   CLIENT_SHARE=$(echo "$RESPONSE" | jq -r .client_share)
   echo "Save this client_share permanently: $CLIENT_SHARE"

5. 5

   Read it back by sending your share in X-Client-Share. Without the header the read fails.

   bash Copy

   curl -s https://api.1claw.co/v1/vaults/$VAULT_ID/secrets/api-keys/stripe \
     -H "Authorization: Bearer $TOKEN" \
     -H "X-Client-Share: $CLIENT_SHARE"

The vault now returns a client_share on write and requires it on read, so 1Claw alone cannot reconstruct the DEK.

Where this goes wrong in practice. Threshold schemes are mathematically sound and operationally demanding, and the gap between those two is where incidents live.

• Custody mode is immutable, and it is chosen early. The decision is made during a spike, by whoever is setting up the vault, usually before anyone has thought about who will hold a share in a year.
• The client share has no owner. A share held by "the team" is held by nobody. It needs a named custodian, a documented location, and a successor.
• The X-Client-Share header is forgotten in one path. Client-custody modes require it on every read, and the service that was written last, or by a different team, is the one that discovers this in production.
• Availability is confused with security. 2-of-3 tolerates losing one share; 2-of-2 tolerates nothing. Teams pick 2-of-2 for its stronger trust property and discover the availability cost during an incident.