Skip to content

feat(kyc-controller): add VendorOnboardingController that follows the step kyc-api decides - #11441

Open
georgeweiler wants to merge 34 commits into
mainfrom
gw/kyc-flow-controller
Open

georgeweiler wants to merge 34 commits into
mainfrom
gw/kyc-flow-controller

Conversation

@georgeweiler

@georgeweiler georgeweiler commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor

Explanation

KycController keeps one flat session and works out where the user is on the phone. For Kalshi (and later VBA) the server should decide, so the phone cannot drift from it.

This adds VendorOnboardingController to @metamask/kyc-controller, next to KycController. It shares KycService and does not touch KycController or its state.

  • State is only vendors[vendor] = { step, sessionId }. Terms, consents and account link state stay on the server.
  • Actions: refreshStep, acceptTerms (sent to kyc-api at once, no local draft), startAccountLink, verifyAccountLink, startSession, submitPhone, submitPhoneCode, submitEmailCode, resendEmailCode, markProviderSubmitted, reset. Each saves the step kyc-api answers with.
  • startSession opens the UKYC session, or picks up the one kyc-api already has, then wraps and sends the encryption key and capability token. The wrapping lives in ukyc/sessionAuthorization.ts. It does not create a vendor customer, so Iron needs more before it can move here.
  • Account link calls are signed on the device, so the client supplies them through the accountLinkAdapters option.
  • KycService gains getStep, acceptVendorTerms, markProviderSubmitted and postOnboardingStep. createUkycSession accepts the kalshi vendor and an optional email.
  • Steps: KYC_STEPS, KycStep, OnboardingVendor and toKycStep. A step the client does not know becomes error. The list uses confirm_identity, which kyc-api must send too.

KycController.ts keeps its own copy of the key wrapping. It can use the shared helper in a follow-up.

References

POC for a first look: #11439 and consensys-vertical-apps/va-mmcx-kyc-api#94.

Checklist

  • I've updated the test suite for new or updated code as appropriate
  • I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
  • I've communicated my changes to consumers by updating changelogs for packages I've changed
  • I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them

🤖 Generated with Claude Code


Note

High Risk
Touches identity-sharing consent, partner JWT minting, UKYC session crypto, and externally signed Kalshi account-link flows—security- and auth-sensitive paths with broad API surface.

Reviewed by Cursor Bugbot for commit 03022f8. Bugbot is set up for automated code reviews on this repo. Configure here.

Explanation

KycController keeps one flat session and works out on the phone where the user is. For Kalshi (and later Iron) the server should decide, so the phone cannot drift from it.

This adds VendorOnboardingController to @metamask/kyc-controller, next to KycController. It shares KycService and does not touch KycController or its state.

  • State is only vendors[vendor] = { step, status, sessionId }. status sits next to the step because a user asked to redo the identity provider is on the same step as one doing it the first time. Terms, consents and account link state stay on the server.
  • Actions: refreshStep, acceptTerms (sent to kyc-api at once, no local draft), startAccountLink, verifyAccountLink, startSession, fetchSessionDisclaimers, acceptSessionDisclaimers, launchProviderFlow, submitPhone, submitPhoneCode, submitEmailCode, resendEmailCode and reset. Each action reads the step from kyc-api afterwards and saves it.
  • Step reads are ordered. A plain refreshStep joins a read already in flight, while an action always starts its own. An answer that arrives after a newer read, or after reset, is dropped.
  • startSession opens the UKYC session, or picks up the one kyc-api already has. It verifies both encryption schemas' jwtChain, then wraps and sends the encryption key and capability token. The wrapping lives in ukyc/sessionAuthorization.ts and uses the async @metamask/cryptography helpers. It records the identity-sharing consent and mints a partner identity token, which kyc-api takes the session email from. It does not create a vendor customer, so Iron needs more before it can move here.
  • launchProviderFlow presents SumSub through the sumsubLauncher option. It follows the same submission rule as KycController (fix(kyc-controller): don't report submitted when SumSub closes without a submission #11463): a review decision the SDK opens on is not a submission, and a later pre-submission status clears an earlier Pending. It then reads the next step from kyc-api and stores no SumSub result.
  • Account link calls are signed on the device, so the client supplies them through the accountLinkAdapters option.
  • KycService gains getStep, acceptVendorTerms and postOnboardingStep. getStep is the only one that reports a step. fetchVendorDisclaimers, getSessionStatusForVendor and createUkycSession accept the kalshi vendor.
  • Steps: KYC_STEPS, KycStep, KYC_STEP_STATUSES, KycStepStatus, KycStepInfo, OnboardingVendor, KycClientContext, toKycStep and toKycStepStatus. A step the client does not know becomes error, and an unknown status becomes none. The list uses confirm_identity, which kyc-api must send too.

Known open item: #mintPartnerIdentityToken uses the iron audience for every vendor, because IdentitySharingAudience has no Kalshi audience yet. A Kalshi onboarding therefore records an Iron identity-sharing consent. This needs a Kalshi audience in MetaMask Auth, or startSession limited to Iron, before release.

KycController.ts keeps its own copy of the key wrapping. It can use the shared helper in a follow-up.

References

POC for a first look: #11439 and consensys-vertical-apps/va-mmcx-kyc-api#94.

Checklist

  • I've updated the test suite for new or updated code as appropriate
  • I've updated documentation (JSDoc, Markdown, etc.) for new or updated code as appropriate
  • I've communicated my changes to consumers by updating changelogs for packages I've changed
  • I've introduced breaking changes in this PR and have prepared draft pull requests for clients and consumer packages to resolve them

🤖 Generated with Claude Code

Open in Web Open in Cursor 

@georgeweiler georgeweiler changed the title feat(kyc-controller): add KycFlowController that follows the step kyc-api decides feat(kyc-controller): add VendorOnboardingController that follows the step kyc-api decides Nov 11, 2026
georgeweiler and others added 16 commits November 18, 2026 12:21
…-api decides

A new controller next to KycController, sharing KycService. State is only
vendors[vendor] = { step, sessionId }: terms, consents and account link
state stay on the server, so the client cannot disagree with it.

- Actions: refreshStep, acceptTerms, startAccountLink, verifyAccountLink,
  submitPhone, submitPhoneCode, submitEmailCode, resendEmailCode,
  markProviderSubmitted, reset
- KycService: getStep, acceptVendorTerms, markProviderSubmitted,
  postOnboardingStep
- KYC_STEPS, KycStep, KycFlowVendor and toKycStep (an unknown step is error)
- Device-signed account link calls come from the client through
  accountLinkAdapters
- Opening the UKYC session (key wrapping, authorizations) is not here yet

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…ession

Creates the vendor's UKYC session, or picks up the one kyc-api already
has, then wraps the encryption key and a capability token for idOS and
submits them. An existing session only gets fresh authorizations when its
status says new or expired. Does not create a vendor customer.

- ukyc/sessionAuthorization.ts holds the key wrapping, taking plain
  functions so no messenger type has to fit two controllers
- localUserSecret helpers accept any get/set store (types only)
- KycService.createUkycSession accepts the kalshi vendor and an optional
  email

KycController.ts is untouched; it still carries its own copy of the
wrapping code until it is pointed at the shared helper.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
fetchSessionDisclaimers reads the session's documents and acceptSessionDisclaimers
records the consents with kyc-api at once, then reads the next step. Without them
a Kalshi session could not get past the consent part of identity_verification.
credentialReusabilityConsentGiven is an argument, never stored or defaulted.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…umSub

Takes the platform launcher as an option, fetches the access token for the
vendor's session, and tells kyc-api when the user finishes. Reports
submitted, abandoned or failed. Keeps no provider flow state on the phone.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…gController

Renames the controller, its files, state, action and event types and the
changelog entries. KycFlowVendor becomes OnboardingVendor, KycFlowVendorState
becomes OnboardingVendorState and KycFlowProviderOutcome becomes
OnboardingProviderOutcome. The messenger namespace is now
VendorOnboardingController. No behaviour changes.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
…tdated

Overlapping refreshStep calls now share one request to kyc-api. A read that
an action starts never joins an older one, and a step that comes back with an
action (accept terms, provider submitted) cancels reads started before it, so
a slow older read can no longer overwrite the newer step.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
… keep idOS's step

KycService.getStep, acceptVendorTerms, markProviderSubmitted and
postOnboardingStep return idOS's own step with the step. The controller keeps
it as relayStep, saves the step from the code steps and a verified link code
instead of asking again, and the account link adapter can pass the step back.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
identity_verification becomes identity_email_code, identity_phone and
identity_provider, matching kyc-api. The controller no longer keeps idOS's own
step, and the service methods return plain steps again.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
kyc-api no longer reports the step on the routes that change it, so the
controller asks for it once the action has run.

- `KycService.acceptVendorTerms` and `markProviderSubmitted` return
  nothing, and `postOnboardingStep` returns the session status alone.
  `OnboardingStepResult` goes with it
- the step endpoint's field is `step`, not `nextStep`
- `#writeStep` is gone with its last caller. Every action now ends in
  `#readStep`, so the step it reports was computed after the action ran,
  not alongside it
- the per-vendor request counter stays: it is what stops a slow read
  from overwriting a newer one, which is now the only race left
- `KycAccountLinkAdapter.verifyLink` no longer carries `nextStep`

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
kyc-api no longer takes an email on `POST /sessions`: it reads one from
the verified `partnerIdentityToken`, so the address a vendor registers
is the one MetaMask verified and cannot diverge from it.

`startSession` and `createUkycSession` take `partnerIdentityToken` in
place of `email`, and `createAuthorizedSession` passes it through.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
MetaMask Auth answers `403 consent_required` for an audience the user
has not granted, so `getPartnerIdentityToken` has to be paired with
`putIdentitySharingConsent`. The screen called only the second half, so
opening a Kalshi session failed after MFA.

The controller now does both, so they cannot be separated again, and a
test pins the order.

Note the audience is still `iron`, so a Kalshi onboarding records an
Iron consent. That is a consent record against the wrong vendor and
wants a real `kalshi` audience, not just a different token audience.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
kyc-api reports where the user is and how verification is going as two
fields, so the controller stores both. A user asked to redo the identity
provider is on the same step as one doing it the first time; only the
status differs, which is what a banner keys off.

`account_link_code` is gone: the account link is one step with two
client screens, so someone who mistyped their email can go back. The
terminal steps (`kyc_pending`, `kyc_rejected`, `approved`) collapse into
`done`, with the status saying which.

`getStep` also takes a client context for the few facts kyc-api cannot
see. Empty for Kalshi, which has none.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…ubmitted

kyc-api reads the relay's `currentStep` to know whether the applicant
still has something to do, so there is nothing to tell it. Removes
`markProviderSubmitted` from the service and the controller.

`launchProviderFlow` still reads the next step once the SDK completes:
without that read the screen would sit on the provider step, since the
step is what the client acts on.

Also tidies two things from the earlier consent change that lint caught:
`#mintPartnerIdentityToken` took a vendor it never used, because the
audience is fixed, and `getStep`'s client parameter was undocumented.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
… and the SumSub submission rule

Main made the UKYC crypto helpers async (#10798), so sessionAuthorization
now uses the shared generateKeyPair and awaits signStorageAccessToken and
assertAttestedServerPublicKey. Without the await, a failed jwtChain check
would no longer reject the wrapping keys.

Main also replaced isSumSubFlowCompleted (#11463): a review decision the
SDK opens on is no longer a submission, and a later pre-submission status
clears an earlier Pending. launchProviderFlow follows the same rule.

Co-authored-by: george.weiler <george.weiler@consensys.net>
…egenerate action types

Type the handler mocks as Mock so they fit the messenger action handlers,
add the missing status to the reset fixture, and regenerate the
KycService getStep action type for its updated JSDoc.

Co-authored-by: george.weiler <george.weiler@consensys.net>
@cursor
cursor Bot force-pushed the gw/kyc-flow-controller branch from 3019345 to cfd3084 Compare November 18, 2026 12:27
@github-actions

github-actions Bot commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

🛑 Files requiring codeowner review

To merge this PR, you'll need to get approvals from the following owners.

@MetaMask/accounts-engineers (2 files)
  • packages/profile-sync-controller/CHANGELOG.md
  • packages/profile-sync-controller/src/sdk/authentication-jwt-bearer/types.ts
@MetaMask/auth-engineers (4 files)
  • packages/authenticated-user-storage/CHANGELOG.md
  • packages/authenticated-user-storage/src/authenticated-user-storage.test.ts
  • packages/authenticated-user-storage/src/types.ts
  • packages/authenticated-user-storage/src/validators.ts
@MetaMask/universal-kyc (15 files)
  • packages/kyc-controller/ARCHITECTURE.md
  • packages/kyc-controller/CHANGELOG.md
  • packages/kyc-controller/src/index.ts
  • packages/kyc-controller/src/KycApiError.test.ts
  • packages/kyc-controller/src/KycApiError.ts
  • packages/kyc-controller/src/KycService-method-action-types.ts
  • packages/kyc-controller/src/KycService.test.ts
  • packages/kyc-controller/src/KycService.ts
  • packages/kyc-controller/src/types.test.ts
  • packages/kyc-controller/src/types.ts
  • packages/kyc-controller/src/ukyc/localUserSecret.ts
  • packages/kyc-controller/src/ukyc/sessionAuthorization.ts
  • packages/kyc-controller/src/VendorOnboardingController-method-action-types.ts
  • packages/kyc-controller/src/VendorOnboardingController.test.ts
  • packages/kyc-controller/src/VendorOnboardingController.ts

ℹ️ Files co-owned by @MetaMask/core-platform (expand for more)

[!NOTE]
For convenience in maintaining this repo, @MetaMask/core-platform co-owns
the following files. It is not required to seek approval from
@MetaMask/core-platform to change these files. This section is purely
informational.

  • packages/authenticated-user-storage/CHANGELOG.md
  • packages/kyc-controller/CHANGELOG.md
  • packages/profile-sync-controller/CHANGELOG.md

@georgeweiler
georgeweiler marked this pull request as ready for review November 18, 2026 12:29
@georgeweiler
georgeweiler requested review from a team as code owners November 18, 2026 12:29

@cursor cursor Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Stale Bugbot comment from a previous run.

cursoragent and others added 3 commits November 18, 2026 12:37
…set, fix docs

- Test getStep's client context query and toKycStepStatus's fallback.
- Make createAuthorizedSession's partnerIdentityToken required: the only
  caller always mints one and kyc-api takes the session email from it.
- reset outdates step reads in flight so a late answer cannot bring back a
  forgotten vendor.
- Move the #readStep JSDoc back onto #readStep and rename the stale email
  test.
- Changelog: drop the removed createUkycSession email option, add status to
  the state shape, describe the SumSub submission rule and reset.
- ARCHITECTURE.md: describe VendorOnboardingController and its endpoints.

Co-authored-by: George Weiler <georgejweiler@gmail.com>
#write filled a missing vendor entry with a vendor_terms step, so a session
id saved by startSession or a reinstall looked like a user who still had to
accept terms, for good if the step read failed. step and status are now null
until kyc-api answers.

Co-authored-by: George Weiler <georgejweiler@gmail.com>
Co-authored-by: George Weiler <georgejweiler@gmail.com>
@georgeweiler

Copy link
Copy Markdown
Contributor Author

@metamaskbot publish previews

@github-actions

Copy link
Copy Markdown
Contributor

Preview builds have been published. Learn how to use preview builds in other projects.

Expand for full list of packages and versions.
@metamask-previews/account-tree-controller@11.2.0-preview-9726c3b7f
@metamask-previews/accounts-controller@40.2.0-preview-9726c3b7f
@metamask-previews/address-book-controller@8.0.0-preview-9726c3b7f
@metamask-previews/advanced-chart-core@1.1.2-preview-9726c3b7f
@metamask-previews/ai-controllers@2.0.0-preview-9726c3b7f
@metamask-previews/analytics-controller@4.3.1-preview-9726c3b7f
@metamask-previews/analytics-data-regulation-controller@0.0.0-preview-9726c3b7f
@metamask-previews/announcement-controller@9.0.0-preview-9726c3b7f
@metamask-previews/app-metadata-controller@3.0.0-preview-9726c3b7f
@metamask-previews/approval-controller@10.0.0-preview-9726c3b7f
@metamask-previews/assets-controller@20.4.1-preview-9726c3b7f
@metamask-previews/assets-controllers@113.3.2-preview-9726c3b7f
@metamask-previews/authenticated-user-storage@4.2.0-preview-9726c3b7f
@metamask-previews/base-controller@10.1.0-preview-9726c3b7f
@metamask-previews/base-data-service@2.1.0-preview-9726c3b7f
@metamask-previews/bitcoin-regtest-up@2.0.0-preview-9726c3b7f
@metamask-previews/bridge-controller@83.2.0-preview-9726c3b7f
@metamask-previews/bridge-status-controller@78.0.3-preview-9726c3b7f
@metamask-previews/build-utils@4.0.0-preview-9726c3b7f
@metamask-previews/byte-utils@0.1.0-preview-9726c3b7f
@metamask-previews/chain-agnostic-permission@2.1.0-preview-9726c3b7f
@metamask-previews/chomp-api-service@7.1.0-preview-9726c3b7f
@metamask-previews/claims-controller@1.1.0-preview-9726c3b7f
@metamask-previews/client-controller@2.0.0-preview-9726c3b7f
@metamask-previews/client-utils@3.4.0-preview-9726c3b7f
@metamask-previews/compliance-controller@3.0.0-preview-9726c3b7f
@metamask-previews/composable-controller@13.0.0-preview-9726c3b7f
@metamask-previews/config-registry-controller@6.0.0-preview-9726c3b7f
@metamask-previews/connectivity-controller@1.0.0-preview-9726c3b7f
@metamask-previews/controller-utils@13.0.0-preview-9726c3b7f
@metamask-previews/core-backend@14.1.0-preview-9726c3b7f
@metamask-previews/cryptography@1.1.2-preview-9726c3b7f
@metamask-previews/delegation-controller@4.0.0-preview-9726c3b7f
@metamask-previews/earn-controller@13.1.0-preview-9726c3b7f
@metamask-previews/eip-5792-middleware@4.1.1-preview-9726c3b7f
@metamask-previews/eip-7702-internal-rpc-middleware@1.0.0-preview-9726c3b7f
@metamask-previews/eip1193-permission-middleware@3.0.0-preview-9726c3b7f
@metamask-previews/error-utils@0.1.0-preview-9726c3b7f
@metamask-previews/eth-block-tracker@16.0.0-preview-9726c3b7f
@metamask-previews/eth-json-rpc-middleware@26.0.1-preview-9726c3b7f
@metamask-previews/eth-json-rpc-provider@7.0.0-preview-9726c3b7f
@metamask-previews/eth-sig-util@10.0.1-preview-9726c3b7f
@metamask-previews/foundryup@2.0.0-preview-9726c3b7f
@metamask-previews/gas-fee-controller@27.1.1-preview-9726c3b7f
@metamask-previews/gator-permissions-controller@6.1.2-preview-9726c3b7f
@metamask-previews/geolocation-controller@2.0.0-preview-9726c3b7f
@metamask-previews/java-tron-up@2.0.0-preview-9726c3b7f
@metamask-previews/json-rpc-engine@11.0.0-preview-9726c3b7f
@metamask-previews/json-rpc-middleware-stream@9.0.0-preview-9726c3b7f
@metamask-previews/key-tree@11.0.0-preview-9726c3b7f
@metamask-previews/keyring-controller@28.2.2-preview-9726c3b7f
@metamask-previews/kyc-controller@0.16.0-preview-9726c3b7f
@metamask-previews/local-node-utils@2.0.0-preview-9726c3b7f
@metamask-previews/logging-controller@10.0.0-preview-9726c3b7f
@metamask-previews/marketing-consent-controller@1.1.0-preview-9726c3b7f
@metamask-previews/message-manager@15.0.1-preview-9726c3b7f
@metamask-previews/messenger@3.0.0-preview-9726c3b7f
@metamask-previews/messenger-cli@1.0.0-preview-9726c3b7f
@metamask-previews/mfa-recovery-controller@0.1.0-preview-9726c3b7f
@metamask-previews/money-account-api-data-service@2.4.0-preview-9726c3b7f
@metamask-previews/money-account-balance-service@3.2.1-preview-9726c3b7f
@metamask-previews/money-account-controller@3.0.1-preview-9726c3b7f
@metamask-previews/money-account-lifecycle-controller@1.1.0-preview-9726c3b7f
@metamask-previews/money-account-mfa-whitelist@0.3.0-preview-9726c3b7f
@metamask-previews/money-account-upgrade-controller@7.0.0-preview-9726c3b7f
@metamask-previews/money-account-utils@2.2.1-preview-9726c3b7f
@metamask-previews/multichain-account-service@14.1.0-preview-9726c3b7f
@metamask-previews/multichain-api-middleware@5.1.1-preview-9726c3b7f
@metamask-previews/multichain-network-controller@4.1.1-preview-9726c3b7f
@metamask-previews/multichain-transactions-controller@8.0.0-preview-9726c3b7f
@metamask-previews/name-controller@10.0.0-preview-9726c3b7f
@metamask-previews/network-connection-banner-controller@1.1.0-preview-9726c3b7f
@metamask-previews/network-controller@38.0.1-preview-9726c3b7f
@metamask-previews/network-enablement-controller@7.1.3-preview-9726c3b7f
@metamask-previews/node-utils@0.1.0-preview-9726c3b7f
@metamask-previews/notification-services-controller@30.1.0-preview-9726c3b7f
@metamask-previews/passkey-controller@4.1.0-preview-9726c3b7f
@metamask-previews/permission-controller@14.1.0-preview-9726c3b7f
@metamask-previews/permission-log-controller@6.0.0-preview-9726c3b7f
@metamask-previews/perps-controller@24.1.0-preview-9726c3b7f
@metamask-previews/phishing-controller@18.3.1-preview-9726c3b7f
@metamask-previews/platform-api-docs@0.2.1-preview-9726c3b7f
@metamask-previews/polling-controller@17.0.0-preview-9726c3b7f
@metamask-previews/preferences-controller@24.0.0-preview-9726c3b7f
@metamask-previews/profile-controller@3.1.0-preview-9726c3b7f
@metamask-previews/profile-metrics-controller@5.2.2-preview-9726c3b7f
@metamask-previews/profile-sync-controller@36.1.2-preview-9726c3b7f
@metamask-previews/ramps-controller@30.0.0-preview-9726c3b7f
@metamask-previews/rate-limit-controller@8.0.0-preview-9726c3b7f
@metamask-previews/react-data-query@2.0.0-preview-9726c3b7f
@metamask-previews/remote-feature-flag-controller@7.0.0-preview-9726c3b7f
@metamask-previews/sample-controllers@6.1.0-preview-9726c3b7f
@metamask-previews/seedless-onboarding-controller@12.1.0-preview-9726c3b7f
@metamask-previews/selected-network-controller@27.1.0-preview-9726c3b7f
@metamask-previews/sentinel-api-service@2.3.0-preview-9726c3b7f
@metamask-previews/shield-controller@7.1.2-preview-9726c3b7f
@metamask-previews/signature-controller@40.1.1-preview-9726c3b7f
@metamask-previews/smart-transactions-controller@27.3.0-preview-9726c3b7f
@metamask-previews/snap-account-service@4.0.0-preview-9726c3b7f
@metamask-previews/social-controllers@3.22.0-preview-9726c3b7f
@metamask-previews/solana-test-validator-up@2.0.0-preview-9726c3b7f
@metamask-previews/stellar-quickstart-up@0.0.0-preview-9726c3b7f
@metamask-previews/storage-service@2.0.0-preview-9726c3b7f
@metamask-previews/subscription-controller@15.2.2-preview-9726c3b7f
@metamask-previews/transaction-controller@74.2.0-preview-9726c3b7f
@metamask-previews/transaction-pay-controller@32.0.0-preview-9726c3b7f
@metamask-previews/transaction-pay-middleware@2.0.4-preview-9726c3b7f
@metamask-previews/type-utils@0.1.0-preview-9726c3b7f
@metamask-previews/user-operation-controller@42.1.2-preview-9726c3b7f
@metamask-previews/utils@12.0.2-preview-9726c3b7f
@metamask-previews/wallet@21.0.3-preview-9726c3b7f
@metamask-previews/watch-only-account-service@0.1.0-preview-9726c3b7f

@adonesky1
adonesky1 added this pull request to stack #11675 November 19, 2026 21:08
@jiexi
jiexi removed this pull request from stack #11675 November 19, 2026 21:57
georgeweiler and others added 3 commits November 19, 2026 13:57
…1634)

<!-- CURSOR_AGENT_PR_BODY_BEGIN -->
## Explanation

Kalshi onboarding goes through the idOS relay passthrough. The phone
signs `enrollment/intents`, `users/link`, and `users/link/verify` into
`KycSignedRequest` objects (`{ path, headers, body }`) with the nine
relay headers. `body` is the exact signed string: empty for the intent,
`JSON.stringify({ email })` for the link, and `JSON.stringify({ code })`
for verify. Signatures last 60 seconds, so the controller signs
immediately before each call. kyc-api forwards the objects unchanged.

`startSession` for Kalshi sends `email` and `signedRequests`
(`[enrollment/intents, users/link]`, or `[users/link]` when `intentOpen`
is set). It sends no partner identity token, which kyc-api ignores.
`resendEmailCode` sends `{ signedRequest }` with a fresh `users/link`.
`submitEmailCode` sends `{ signedRequest }` with `users/link/verify` and
no `otp`. Iron does not sign.

The controller checks each signer answer against the route and kyc-api's
limits: at most 16 string headers, and a body of at most 4 KB.

`KycService` throws `KycApiError` with the `code` from `{ code, message
}`. When the body's message does not already contain that code, the code
is written into the error message too, so a wrapped failure (which keeps
only the message) still names it. `getKycKalshiErrorCode` reads `code`
or the message. The known codes are the relay's `kalshi_*` codes,
`invalid_or_expired_code`, `session_not_in_email_verification`,
`kalshi_account_exists`, `not_found`, and `idos_relay_unavailable`.

The steps kyc-api returns are `terms`, `mfa`, `kalshi_email_link`,
`kalshi_phone_link`, `sumsub`, and `decision`. Kalshi uses all of them.
Iron uses `terms`, `mfa`, `sumsub`, and `decision`.

`startAccountLink`, `verifyAccountLink`, and `KycAccountLinkAdapter` are
removed.

## References

* Mobile consumer: MetaMask/metamask-mobile#40094
* kyc-api: the passthrough client shape in
consensys-vertical-apps/va-mmcx-kyc-api#108

## Checklist

- [x] I've updated the test suite for new or updated code as appropriate
- [x] I've updated documentation (JSDoc, Markdown, etc.) for new or
updated code as appropriate
- [x] I've communicated my changes to consumers by [updating changelogs
for packages I've
changed](https://github.com/MetaMask/core/tree/main/docs/processes/updating-changelogs.md)
- [x] I've introduced [breaking
changes](https://github.com/MetaMask/core/tree/main/docs/processes/breaking-changes.md)
in this PR and have prepared draft pull requests for clients and
consumer packages to resolve them

<!-- CURSOR_AGENT_PR_BODY_END -->

<div><a
href="https://cursor.com/agents/bc-467c1980-2f32-579f-9926-c15613f6e77b?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-web-light.png"><img
alt="Open in Web" width="114" height="28"
src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a>&nbsp;<a
href="https://cursor.com/background-agent?bcId=bc-467c1980-2f32-579f-9926-c15613f6e77b&cursor_ref=pr_footer&cursor_cta=open_in_cursor"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img
alt="Open in Cursor" width="131" height="28"
src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a>&nbsp;</div>

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **High Risk**
> Breaking API changes (removed account-link actions, new step names,
new constructor option) plus Kalshi session/email flows that depend on
timely device signing and correct relay error handling.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
31a37f3. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
…roller

- acceptTerms -> recordVendorDisclaimers
- acceptSessionDisclaimers -> recordSessionDisclaimers

Action types, exports, tests, and docs updated to match.

Co-authored-by: Cursor <cursoragent@cursor.com>
residenceCountry,
aal2Token: params.aal2Token,
partnerIdentityToken,
...kalshiSigning,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

i don't think it's a good idea for us to have included signedRequests at the root of our POST /sessions request body

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

let's just figure this out later

Comment on lines +720 to +725
const invalid = signed.find((each) => !isWithinSignedRequestLimits(each));
if (invalid) {
throw new Error(
`VendorOnboardingController: signer for ${vendor} returned a request kyc-api would refuse (at most ${KYC_SIGNED_REQUEST_LIMITS.headerCount} headers, all strings, and ${KYC_SIGNED_REQUEST_LIMITS.bodyBytes} body bytes).`,
);
}

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

feels like this isn't something that will happen frequently and is something we can just delegate to the kyc-api to return an error instead? Putting this here also makes it so that we can't adjust these limits on the kyc-api and have them reflect in the client

@adonesky1
adonesky1 added this pull request to stack #11694 November 20, 2026 17:22
@jiexi
jiexi removed this pull request from stack #11694 November 20, 2026 18:37
## Explanation

MetaMask Auth now issues partner identity tokens with `audience:
"kalshi"`. Onboarding still minted every token for `iron`, and skipped
minting entirely for Kalshi, so kyc-api had only the email the client
typed.

`IdentitySharingAudience` and `OidcTokenAudience` now include `kalshi`.
`VendorOnboardingController` records consent for the vendor it is
onboarding and mints the token for that audience, including Kalshi. The
typed email is still sent, because that is the string the phone signs
into `users/link`. kyc-api checks it against the token's verified
`ext.email`.

This follows the merged passthrough in
#11634. The matching kyc-api change
verifies the token.

## References

* Related to #11634

## Checklist

- [x] I've updated the test suite for new or updated code as appropriate
- [x] I've updated documentation (JSDoc, Markdown, etc.) for new or
updated code as appropriate
- [x] I've communicated my changes to consumers by [updating changelogs
for packages I've
changed](https://github.com/MetaMask/core/tree/main/docs/processes/updating-changelogs.md)
- [ ] I've introduced [breaking
changes](https://github.com/MetaMask/core/tree/main/docs/processes/breaking-changes.md)
in this PR and have prepared draft pull requests for clients and
consumer packages to resolve them

Made with [Cursor](https://cursor.com)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Touches authentication consent and partner token minting for vendor
onboarding; Kalshi session creation behavior changes (email no longer
sent to kyc-api).
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
ff0b099. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
@jiexi
jiexi requested review from a team as code owners November 20, 2026 19:24

@cursor cursor Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit 404da10. Configure here.

? []
: [{ operation: 'enrollment/intents' as const }]),
{ operation: 'users/link' as const, email },
]);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Kalshi email can diverge from token

High Severity

startSession still signs the caller-supplied Kalshi email into users/link while kyc-api now takes the session email from the partner identity token's ext.email. Nothing reads that claim or checks the two addresses match, so a typed address can disagree with the verified one the relay registers. KycController already extracts the token email for this reason.

Additional Locations (1)
Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit 404da10. Configure here.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

unclear to me why this is being introduced

* signature lasts 60 seconds, so sign right before this call. Omitted for
* vendors that do not link an account this way.
*/
signedRequests?: readonly KycSignedRequest[];

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

reminder to look into nesting this or something

* could record them. Needed where a vendor cannot be told about an
* acceptance until an account exists.
*/
vendorTermsAcceptedLocally?: boolean;

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

this isn't sufficient for the server to know if terms have to be shown or not. It has to know precisely what terms were accepted

* @returns The client context to send.
*/
#clientContext(_vendor: OnboardingVendor): KycClientContext {
return {};

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

how are we setting this right now?

This branch was previously deployed

1 inactive (outdated) deployment
default-branch — cfd3084f Deployed Nov 18, 2026 by georgeweiler via Determine whether this PR is a release PR #7288
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.

3 participants