Skip to content

fix(awm): bind encrypted MPC state blobs to their flow context - #301

Open
Marzooqa wants to merge 1 commit into
masterfrom
marzooqanaeemakather/wci-2169-advanced-wallets-eddsa-r-share
Open

Marzooqa wants to merge 1 commit into
masterfrom
marzooqanaeemakather/wci-2169-advanced-wallets-eddsa-r-share

Conversation

@Marzooqa

@Marzooqa Marzooqa commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Binds every encrypted MPC state blob AWM seals to the context it was created for, and verifies that binding before any unseal:

  • New stateBinding helper (advancedWalletManager/handlers/utils/stateBinding.ts): seal/unseal with AEAD associated data of the form <domain>:v1|k=v|.... The adata is covered by the AES-GCM tag, so it cannot be stripped or altered without breaking decryption and cannot be forged without the KMS data key.
  • EdDSA MPCv1 signing R-share envelope: the pinned SDK seals it without adata, so the commitment round wraps the SDK envelope in a bound outer envelope keyed to source|pub|sha256(signable)|derivationPath; the R and G rounds verify and peel the wrapper before handing the inner envelope to the SDK.
  • EdDSA MPCv1 keygen initialize→finalize state: bound to source|coin.
  • ECDSA MPCv2 keygen state (initialize/rounds 1–4/finalize): bound to source plus the consuming stage (round 1..4 / finalize), so a state blob sealed for one round slot cannot be replayed into another.
  • MPCv2 signing (ECDSA and EdDSA): already validates associated data inside the SDK and is unchanged. Note: the pinned SDK beta predates the single-use/expiry/GPG-pin hardening now merged in BitGoJS; AWM picks those up at the next SDK version bump (test fixtures passing mock GPG keys will need the pinned BitGo MPCv2 pub key at that point).
  • Fail-closed: blobs without a matching binding, including legacy pre-binding blobs, are rejected with a 400 instructing the caller to restart the session. MBE, API codecs, and wire formats are unchanged — the binding travels inside the opaque encrypted blobs, so signer and relay do not need a coordinated upgrade.

Known residuals (follow-ups): binding is not single-use — replaying a blob into its own original context is still accepted (mitigated for MPCv2 signing by the SDK's in-process single-use once the SDK is bumped); keygen state binds only the request-available discriminators above, so a same-context replay across ceremonies is not rejected by the binding.

Test plan

  • signMpcTransaction.test.ts: new cases — a keygen-flow blob replayed into the R round is rejected without plaintext disclosure, an unbound legacy blob is rejected, and a blob bound to another signable is rejected; the existing commitment→R→G E2E is unchanged.
  • mpcFinalize.test.ts: finalize fixtures resealed with the binding; new cross-source and cross-coin replay rejections.
  • postMpcV2Key.test.ts: new cross-source replay rejection on mpcv2/round; the out-of-sequence round tests now expect the binding rejection (the check fires before the state's own round comparison).
  • Full src/__tests__/api/advancedWalletManager suite: 97 passing, 0 failing.
  • npx tsc --noEmit shows one pre-existing error in recoveryEcdsa.test.ts (RecoverOptions.userKey), verified present on master.

Release notes

  • Deploying this change drains in-flight flows: any signing or keygen ceremony spanning the deploy fails its next round and must restart (signing retries automatically; a mid-deploy wallet creation restarts keygen).
  • Rolling back this change silently removes binding enforcement (old code ignores adata) — same class as the BitGoJS offline-signing rollouts.

Ticket: WCI-2169

@linear-code

linear-code Bot commented Nov 12, 2026

Copy link
Copy Markdown

WCI-2169

Every encrypted state blob AWM seals now carries AEAD associated data
naming its flow, blob type, source, wallet pub and signable, and every
unseal site recomputes the expected context from the request and rejects
a mismatch before any plaintext is decrypted or returned. Blobs replayed
across flows (for example keygen state into the EdDSA R-share round),
across wallets, or across signing sessions are rejected without
disclosing plaintext.

The EdDSA R-share envelope gets an additional wrapper applied at the
commitment round because the pinned SDK seals it without associated
data; the R and G rounds verify the wrapper before handing the inner
envelope to the SDK. MPCv2 signing already validates associated data
inside the SDK and is unchanged. Legacy blobs without a binding are
rejected fail-closed; flows spanning a deploy must be restarted.

Ticket: WCI-2169
@Marzooqa
Marzooqa force-pushed the marzooqanaeemakather/wci-2169-advanced-wallets-eddsa-r-share branch from e279212 to e1182d8 Compare November 13, 2026 14:36
@Marzooqa
Marzooqa marked this pull request as ready for review November 13, 2026 15:04
@Marzooqa
Marzooqa requested review from a team as code owners November 13, 2026 15:04

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review for a one-time review, or @claude review always to subscribe this PR to a review on every future push.

Tip: disable this comment in your organization's Code Review settings.

@danielpeng1

Copy link
Copy Markdown
Contributor

@claude

@github-actions

Copy link
Copy Markdown

Review: bind encrypted MPC state blobs to flow context

I read the full diff, including the seal/unseal helper, all six handler changes and the tests. The approach is sound. Putting the context in the AEAD associated data (AAD) and failing closed is the right way to close the cross-flow decryption-oracle hole. I found no key material, plaintext or blob contents logged or returned on the new error paths. The findings below are all non-blocking, though the first two are worth fixing before merge.

Findings

1. decodeURIComponent can throw, which turns a bad blob into a 500 (stateBinding.ts, openStateBlob)

storedAdata comes from the caller-supplied blob. Any adata containing a malformed escape, such as "%" or "%E0%A4%A", makes decodeURIComponent throw URIError. That is outside the try/catch, so the caller gets a 500 instead of the BadRequestError the helper promises. Move the decode inside a guard that maps failure to BadRequestError(STATE_BINDING_MISMATCH_ERROR). It is also worth a test with a malformed-escape adata.

2. The AAD is only enforced if bitgo.decrypt verifies it

openStateBlob compares the unauthenticated adata string in the JSON envelope and then calls bitgo.decrypt. The security claim, "cannot be altered without breaking decryption", holds only if the SDK's decrypt passes the envelope's adata to the GCM verification for every envelope version it accepts, including the v1 SJCL path the comment mentions. The tests show the happy path and mismatch rejection, but I don't see a test that edits the stored adata to the expected value on a blob sealed with different AAD and expects decryption to fail. Please add that test. It guards the property the whole PR depends on, and it will catch an SDK bump that changes the behavior.

A failed decrypt of a tampered blob also surfaces as a generic error, so probably a 500. A 400 would match the rest of the fail-closed path.

3. AAD values are not escaped (buildStateBindingAdata)

Values are joined with | and = and no escaping. coin, pub and path (derivationPath from the txRequest) come from the untrusted orchestrator. A derivationPath containing |pub=...|signable=... could make two different tuples serialize to the same string. I don't see a practical collision today, because the parts are in sorted key order and the hash and pub are fixed-format. Still, it's cheap to make this robust. Either reject values containing | or =, or length-prefix or encodeURIComponent each value. This is the kind of thing that bites when someone adds a part later.

4. Keygen state binding is weak across ceremonies (acknowledged residual)

The ECDSA MPCv2 and EdDSA keygen state binds only source plus the round or coin. A malicious orchestrator can splice states from two concurrent keygens for the same source and coin. The PR calls this out, but a follow-up should bind something per-ceremony that the request already carries. The hash of bitgoGpgPub plus counterPartyGpgPub is a candidate, or a random session nonce generated at initialize and echoed back. None of this is single-use either, so a blob can be replayed into its own original context. The SDK bump would cover MPCv2 signing but not keygen.

5. Commitment round now returns an explicit field list (ecdsaEddsaSignTransaction.ts)

The old code spread everything createCommitmentShareFromTxRequest returned. The new code picks userToBitgoCommitment, encryptedSignerShare and encryptedUserToBitgoRShare. If the SDK returns any other field, it is now silently dropped. Please confirm the pinned SDK returns only those three. Spreading ...commitment and then overriding encryptedUserToBitgoRShare would be safer against SDK changes.

6. New hard requirement on derivationPath (getSignableBindingParts)

The commitment round now throws a 400 if unsignedTx.derivationPath is missing. Please confirm the SDK never accepts a txRequest without one. If it defaults to m/0 when absent, wallets that previously signed will now fail. Also, the 400 is thrown after createCommitmentShareFromTxRequest has run, so the work is wasted. Compute the AAD first and fail early.

7. Rollout

The PR text says signer and relay need no coordinated upgrade, which is true for the wire format. But any in-flight keygen or signing session across the deploy now fails with a 400 and needs a restart. That seems acceptable, but it belongs in the release notes, which are currently empty.

Nits

  • STATE_BINDING_MISMATCH_ERROR tells the caller to "restart the session" for every failure. That's fine for UX. Logging the mismatch server-side, with domain only and no blob data, would help operators spot replay attempts.
  • StateBindingBitGo is a hand-rolled structural type. If the SDK exports a type for the encryption session, use it, so API drift becomes a compile error.

Tests

The coverage is good: cross-flow replay, an unbound legacy blob, a different signable, and cross-source and cross-coin keygen replay. Still missing:

  • tampered or malformed adata (findings 1 and 2);
  • a non-replay positive check that a round-N blob is rejected in round N+1 for MPCv2 keygen. The updated out-of-sequence tests partly cover this.

Overall the change is a clear improvement. I'd fix findings 1 and 2 and confirm 5 and 6 before merge.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants