Repository navigation
feat(kyc-controller): add VendorOnboardingController that follows the step kyc-api decides - #11441
georgeweiler wants to merge 34 commits into
Conversation
…-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>
3019345 to
cfd3084
Compare
🛑 Files requiring codeowner reviewTo merge this PR, you'll need to get approvals from the following owners. @MetaMask/accounts-engineers (2 files)
@MetaMask/auth-engineers (4 files)
@MetaMask/universal-kyc (15 files)
@MetaMask/core-platform (expand for more) |
…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>
|
@metamaskbot publish previews |
|
Preview builds have been published. Learn how to use preview builds in other projects. Expand for full list of packages and versions. |
…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> <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> </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, |
There was a problem hiding this comment.
i don't think it's a good idea for us to have included signedRequests at the root of our POST /sessions request body
| 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).`, | ||
| ); | ||
| } |
There was a problem hiding this comment.
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
## 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>
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.
❌ 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 }, | ||
| ]); |
There was a problem hiding this comment.
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)
Reviewed by Cursor Bugbot for commit 404da10. Configure here.
There was a problem hiding this comment.
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[]; |
There was a problem hiding this comment.
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; |
There was a problem hiding this comment.
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 {}; |
There was a problem hiding this comment.
how are we setting this right now?


Explanation
KycControllerkeeps 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
VendorOnboardingControllerto@metamask/kyc-controller, next toKycController. It sharesKycServiceand does not touchKycControlleror its state.vendors[vendor] = { step, sessionId }. Terms, consents and account link state stay on the server.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.startSessionopens 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 inukyc/sessionAuthorization.ts. It does not create a vendor customer, so Iron needs more before it can move here.accountLinkAdaptersoption.KycServicegainsgetStep,acceptVendorTerms,markProviderSubmittedandpostOnboardingStep.createUkycSessionaccepts thekalshivendor and an optionalemail.KYC_STEPS,KycStep,OnboardingVendorandtoKycStep. A step the client does not know becomeserror. The list usesconfirm_identity, which kyc-api must send too.KycController.tskeeps 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
🤖 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
KycControllerkeeps 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
VendorOnboardingControllerto@metamask/kyc-controller, next toKycController. It sharesKycServiceand does not touchKycControlleror its state.vendors[vendor] = { step, status, sessionId }.statussits 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.refreshStep,acceptTerms(sent to kyc-api at once, no local draft),startAccountLink,verifyAccountLink,startSession,fetchSessionDisclaimers,acceptSessionDisclaimers,launchProviderFlow,submitPhone,submitPhoneCode,submitEmailCode,resendEmailCodeandreset. Each action reads the step from kyc-api afterwards and saves it.refreshStepjoins a read already in flight, while an action always starts its own. An answer that arrives after a newer read, or afterreset, is dropped.startSessionopens 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 inukyc/sessionAuthorization.tsand uses the async@metamask/cryptographyhelpers. 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.launchProviderFlowpresents SumSub through thesumsubLauncheroption. It follows the same submission rule asKycController(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 earlierPending. It then reads the next step from kyc-api and stores no SumSub result.accountLinkAdaptersoption.KycServicegainsgetStep,acceptVendorTermsandpostOnboardingStep.getStepis the only one that reports a step.fetchVendorDisclaimers,getSessionStatusForVendorandcreateUkycSessionaccept thekalshivendor.KYC_STEPS,KycStep,KYC_STEP_STATUSES,KycStepStatus,KycStepInfo,OnboardingVendor,KycClientContext,toKycStepandtoKycStepStatus. A step the client does not know becomeserror, and an unknown status becomesnone. The list usesconfirm_identity, which kyc-api must send too.Known open item:
#mintPartnerIdentityTokenuses theironaudience for every vendor, becauseIdentitySharingAudiencehas no Kalshi audience yet. A Kalshi onboarding therefore records an Iron identity-sharing consent. This needs a Kalshi audience in MetaMask Auth, orstartSessionlimited to Iron, before release.KycController.tskeeps 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
🤖 Generated with Claude Code